feat(selfhosted): add client-side MCP tools - #17

Hand-written change from the internal SDK repository — not produced by make vendor.

• source subject: feat(selfhosted): add client-side MCP tools
• reason: No Ark-APIs provenance marker; treated as a hand-written source commit.

简述

为 Java self-hosted worker 增加 client-side MCP tools，并适配当前 Managed Agents Custom Tool 契约。core 保持 Java 8，可选 ark-runtime-mcp 使用 Java 17 和官方 MCP Java SDK 2.0；同时修复 OkHttp retry 的等待时间、服务端提示与重试标记。

改动

• core 增加协议无关 MCP Client、ToolDefinition、结果模型和 Custom Tool 转换。
• 可选 com.volcengine:ark-runtime-mcp 使用 MCP Java SDK 2.0 的完整 Map Schema。
• 支持 text、image、embedded resource、PDF 与 structured content。
• type/properties/required 结构化传递，property 内本地引用内联，其余有效顶层约束以紧凑 JSON 写入 tool description。
• JSON Pointer 保留末尾空 token，符合合法本地引用语义。
• 为 ark-runtime-mcp:0.6.0 补齐 Maven Central 元数据、sources/javadocs/GPG 配置和发布步骤；core 继续产出 Java 8 bytecode，发布作业使用 JDK 17。
• MCP 凭证和连接仅保留在 worker 侧。

SDK retry 修复

• 默认最大重试次数保持 2 次；首次等待改为 0.5 秒基数，之后指数增长并封顶 8 秒，每次减去 0–25% jitter。
• 使用纳秒 Duration 计算等待时间，保留亚秒退避。
• 优先读取 Retry-After-Ms，其次读取 Retry-After；支持小数数值以及 RFC 1123 HTTP-date。
• 首次请求和后续重试分别携带 X-Stainless-Retry-Count: 0/1/2，调用方显式设置该 header 时保留调用方值。
• 支持 X-Should-Retry 显式控制，并将 408、409、429、5xx 统一视为可重试状态。
• 等待前关闭失败响应，避免退避期间占用连接。
• heartbeat/lifecycle 继续保持单次请求，但明确携带 retry-count=0，便于网关识别请求是否属于重试。

其他行为修复

• 文本 content block 即使内容为空也保留 MA 契约必需的 text 字段。
• MCP 返回 isError=true 且没有内容时，生成 tool returned an error，避免空错误结果。
• embedded resource 转换失败时不再把 URI 写入 tool result，避免 signed URL 或查询凭证进入 MA、模型和日志。
• property 内已成功内联的 $defs/definitions 不再重复写入 description；仍被其他约束引用时继续保留。
• 不修改 MA 或 Agent Loop，仍适配现网 type/properties/required 三字段 Custom Tool 契约。

测试

• core: mvn test：66 passed
• core: mvn checkstyle:check、mvn package -DskipTests
• retry 新增 server delay 优先级、亚秒退避、retry-count、自定义 header、显式重试控制及单次 heartbeat 测试。
• MCP module: mvn test、mvn package
• 新临时目录按 0.6.0 安装 core 后构建 MCP artifact 成功。
• public profile 成功生成 jar、sources、javadocs，并确认 LICENSE/THIRD_PARTY_NOTICES 入包。
• GitHub Actions actionlint
• 独立 STG harness 已验证同一 MA Custom Tool 事件契约全链路。

示例与运行时修复

• 新增独立 Java 17 examples/self_hosted_mcp_worker module，以最小粒度展示 tools/list -> Custom Tool 定义 -> MCP Tool 执行 -> EnvironmentWorker.run。
• 内置最小 stdio mcp_echo server；示例不负责创建 Agent、Session 或消费 SSE。
• 真实 stdio 握手发现 core Jackson annotations 2.18.8 会覆盖 MCP Java SDK 2.0 所需的 2.20 并触发 NoSuchMethodError；现仅在可选 ark-runtime-mcp 模块固定 annotations 2.20，不修改 core 依赖。
• 新增官方 MCP JSON mapper 回归测试，并在 CI 中编译独立示例。

See merge request: !91

Sync-Source-Commit: e5831b340cab896b853cd9555722ea7b4e917809
Hand-Written-Reason: No Ark-APIs provenance marker; treated as a hand-written source commit.
Release-Version: 0.6.0

Created by ark-hand.